import WebpackLicense from '@components/WebpackLicense';
import { ApiMeta } from '@components/ApiMeta';

<WebpackLicense from="https://webpack.js.org/api/module-methods/" />

# Module methods

This section covers all methods available in code compiled with Rspack. When using Rspack to bundle your application, you can pick from a variety of module syntax styles including [ES modules](https://nodejs.org/api/esm.html#modules-ecmascript-modules) and [CommonJS](https://nodejs.org/api/modules.html).

While Rspack supports multiple module syntaxes, we recommend following a single syntax for consistency and to avoid odd behaviors or bugs.

Actually Rspack would enforce the recommendation for `.mjs` files, `.cjs` files or `.js` files when their nearest parent `package.json` file contains a ["type"](https://nodejs.org/api/packages.html#type) field with a value of either `"module"` or `"commonjs"`. Please pay attention to these enforcements before you read on:

- `.mjs` or `.js` with `"type": "module"` in package.json
  - No CommonJS allowed, for example, you can't use `require`, `module.exports` or `exports`
  - File extensions are required when importing, e.g, you should use import './src/App.mjs' instead of import './src/App' (you can disable this enforcement with Rule.resolve.fullySpecified)
- `.cjs` or `.js` with "type": "commonjs" in package.json
  - Neither import nor export is available

## ES modules (recommended)

Rspack support ES modules syntax natively, you can use static `import`, `export` and `import()` syntax.

:::warning
Keep in mind that you will still probably need SWC or Babel for other ES6+ features.
:::

### import

Statically `import` the `export` of another module.

```js
import MyModule from './my-module.js';
import { NamedExport } from './other-module.js';
```

You can also `import` Data URI, this allow you to embed Base64 encoded JavaScript code directly in the import statement:

```js
// Equivalent to import a module that contains `console.log('hello')`
import 'data:text/javascript;charset=utf-8;base64,Y29uc29sZS5sb2coJ2hlbGxvJyk=';

// Equivalent to import a module that contains `export const number = 42;`
import { number } from 'data:text/javascript;charset=utf-8;base64,ZXhwb3J0IGNvbnN0IG51bWJlciA9IDQyOw==';
```

### export

Export anything as a `default` or named export.

```js
// Named exports
export var Count = 5;
export function Multiply(a, b) {
  return a * b;
}

// Default export
export default {
  // Some data...
};
```

### Dynamic import()

```ts
function import(path: string): Promise;
```

Dynamically load modules, see [Dynamic import](/guide/optimization/code-splitting#dynamic-import) for more details.

Calls to `import()` are treated as split points, meaning the requested module and its children are split out into a separate chunk.

```js
if (module.hot) {
  import('lodash').then(_ => {
    // Do something with lodash (a.k.a '_')...
  });
}
```

:::warning
This feature relies on `Promise` internally. If you use `import()` with legacy browsers, remember to shim `Promise` using a polyfill such as [core-js](https://github.com/zloirock/core-js), [es6-promise](https://github.com/stefanpenner/es6-promise) or [promise-polyfill](https://github.com/taylorhakes/promise-polyfill).
:::

#### Dynamic expressions in import()

It is not possible to use a fully dynamic import statement, such as `import(foo)`. Because `foo` could potentially be any path to any file in your system or project.

The `import()` must contain at least some information about where the module is located. Bundling can be limited to a specific directory or set of files so that when you are using a dynamic expression, every module that could potentially be requested on an `import()` call is included.

For example, `import(`./locale/$\{language}.json`)` will cause every `.json` file in the `./locale` directory to be bundled into the new chunk. At run time, when the variable `language` has been computed, any file like `english.json` or `german.json` will be available for consumption.

```js
// imagine we had a method to get language from cookies or other storage
const language = detectVisitorLanguage();
import(`./locale/${language}.json`).then(module => {
  // do something with the translations
});
```

#### Magic comments

<ApiMeta specific={['Rspack', 'Webpack']} />

Inline comments to make features work. By adding comments to the import, we can do things such as specify chunk name or select different loading modes. For a full list of these magic comments see the code below followed by an explanation of what these comments do.

```js
// Single target
import(
  /* webpackChunkName: "my-chunk-name" */
  /* webpackMode: "lazy" */
  /* webpackExports: ["default", "named"] */
  /* webpackFetchPriority: "high" */
  'module'
);

// Multiple possible targets
import(
  /* webpackInclude: /\.json$/ */
  /* webpackExclude: /\.noimport\.json$/ */
  /* webpackChunkName: "my-chunk-name" */
  /* webpackMode: "lazy" */
  /* webpackPrefetch: true */
  /* webpackPreload: true */
  `./locale/${language}`
);
```

##### webpackIgnore

- **Type:** `boolean`

When set to `true`, Rspack will skip analysis and bundling processing for the dynamic import. This results in:

1. The module's dependencies will not be analyzed during build time
2. The module will not be bundled into a separate chunk file
3. The import operation will be executed by the browser's native `import()` at runtime

This is particularly useful for dynamically loading ESM third-party libraries from external CDNs, for example:

```js
import('https://esm.sh/react' /* webpackIgnore: true */).then(React => {
  console.log(React.version); // 19.0.0
});
```

`webpackIgnore` also applies to the `new URL()` syntax. By default, Rspack will parse module identifiers in `new URL()` and bundle the referenced module into the build output. When you need Rspack to skip processing a particular `new URL()`, you can add the `webpackIgnore: true` comment:

```js
// Rspack will process this URL and bundle './index.css' into the build output
const url1 = new URL('./index.css', import.meta.url);

// Rspack will ignore this URL and preserve the original module identifier
const url2 = new URL(/* webpackIgnore: true */ './index.css', import.meta.url);
```

##### webpackMode

- **Type:** `"eager" | "lazy" | "weak" | "lazy-once"`
- **Default:** `'lazy'`

Different modes for resolving dynamic imports can be specified. The following options are supported:

- `'lazy'` (default): Generates a lazy-loadable chunk for each `import()`ed module.
- `'lazy-once'`: Generates a single lazy-loadable chunk that can satisfy all calls to `import()`. The chunk will be fetched on the first call to `import()`, and subsequent calls to `import()` will use the same network response. Note that this only makes sense in the case of a partially dynamic statement, e.g. `import("./locales/${language}.json")`, where multiple module paths that can potentially be requested.
- `'eager'`: Generates no extra chunk. All modules are included in the current chunk and no additional network requests are made. A Promise is still returned but is already resolved. In contrast to a static import, the module isn't executed until the call to `import()` is made.
- `'weak'`: Tries to load the module if the module function has already been loaded in some other way (e.g. another chunk imported it or a script containing the module was loaded). A Promise is still returned, but only successfully resolves if the chunks are already on the client. If the module is not available, the Promise is rejected. A network request will never be performed. This is useful for universal rendering when required chunks are always manually served in initial requests (embedded within the page), but not in cases where app navigation will trigger an import not initially served.

##### webpackPrefetch

- **Type:**
  - `number`: chunk prefetch priority
  - `boolean`: `false` means not to prefetch, `true` means priority is `0`

Tells the browser that the resource is probably needed for some navigation in the future, see [Prefetching/Preloading modules](/guide/optimization/code-splitting#prefetchingpreloading-modules) for more details.

##### webpackPreload

- **Type:**
  - `number`: chunk preload priority
  - `boolean`: `false` means not to preload, `true` means priority is `0`

Tells the browser that the resource might be needed during the current navigation, , see [Prefetching/Preloading modules](/guide/optimization/code-splitting#prefetchingpreloading-modules) for more details.

##### webpackChunkName

- **Type:**: `string`

A name for the new chunk.

##### webpackFetchPriority

<ApiMeta addedVersion="1.0.0" />

- **Type:**: `"low" | "high" | "auto"`

Set [`fetchPriority`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/fetchPriority) for specific dynamic imports. It's also possible to set a global default value for all dynamic imports by using the `module.parser.javascript.dynamicImportFetchPriority` option.

##### webpackInclude

<ApiMeta addedVersion="1.0.0" />

- **Type:**: `Regexp`

A regular expression that will be matched against during import resolution. Only modules that match **will be bundled**.

##### webpackExclude

<ApiMeta addedVersion="1.0.0" />

- **Type:**: `Regexp`

A regular expression that will be matched against during import resolution. Any module that matches **will not be bundled**.

:::info
Note that `webpackInclude` and `webpackExclude` options do not interfere with the prefix. eg: `./locale`.
:::

##### webpackExports

<ApiMeta addedVersion="1.0.0" />

- **Type:**: `string | string[]`

Tells webpack to only bundle the specified exports of a dynamically `import()`ed module. It can decrease the output size of a chunk.

## CommonJS

Rspack is also support `CommonJS` syntax natively, you can use `require` and `module.exports` methods.

### require

Synchronously retrieve the exports from another module.

```js
require(dependency: string);
```

### require.resolve

Synchronously retrieves the module ID without executing the module code. This method will include the module in the final bundle. The returned module ID is primarily intended for use with `require.cache[id]` or the Rspack internal `__webpack_require__(id)` function. Direct use of this method should be avoided in most application scenarios.

```js
require.resolve(dependency: string);
```

:::warning
Module ID's type can be a number or a string depending on the `optimization.moduleIds` configuration.
:::

### require.cache

Multiple requires of the same module result in only one module execution and only one export. Therefore a cache in the runtime exists. Removing values from this cache causes new module execution and a new export.

```js
var d1 = require('dependency');
require('dependency') === d1;
delete require.cache[require.resolve('dependency')];
require('dependency') !== d1;
```

### require.context

<ApiMeta specific={['Rspack', 'Webpack']} />

`require.context` is a function specific to webpack that allows you to dynamically require a set of modules.

You can use `require.context` in your code, and Rspack will parse and reference the matching modules during the build process.

:::tip
The return value of `require.context` is the same as [import.meta.webpackContext](/api/runtime-api/module-variables#importmetawebpackcontext). We recommend using `import.meta.webpackContext`, which is more powerful.
:::

- **Type:**

```ts
function requireContext(
  /**
   * A directory to search.
   */
  directory: string,
  /**
   * Whether subdirectories should be searched.
   * @default true
   */
  includeSubdirs?: boolean,
  /**
   * A regular expression to match files.
   * @default /^\.\/.*$/ (any file)
   */
  filter?: RegExp,
  /**
   * Module loading mode.
   * @default 'sync'
   */
  mode?: 'sync' | 'eager' | 'weak' | 'lazy' | 'lazy-once',
): Context;
```

- **Example:**

```js
// Create a context, with files from the test directory that
// can be required with a module specifier ending with `.test.js`.
const context = require.context('./test', false, /\.test\.js$/);
```

```js
// Create a context with all files in the parent folder and
// descending folders ending with `.stories.js`.
const context = require.context('../', true, /\.stories\.js$/);
```

```js
// If mode is set to 'lazy', the underlying modules will be loaded asynchronously
const context = require.context('./locales', true, /\.json$/, 'lazy');
```

:::tip
Rspack uses static analysis to parse the parameters of `require.context` during compilation. Therefore, the parameters must be [literals](https://developer.mozilla.org/en-US/docs/Glossary/Literal).

For example, the value of `filter` cannot be a variable, nor can it be the value generated by `new RegExp()`. It can only be a regular expression literal.
:::

### require.ensure

<ApiMeta specific={['Rspack', 'Webpack']} />

:::tip
`require.ensure()` is specific to rspack/webpack and superseded by `import()`.
:::

Split out the given `dependencies` to a separate bundle that will be loaded asynchronously. When using CommonJS module syntax, this is the only way to dynamically load `dependencies`. Meaning, this code can be run within execution, only loading the dependencies if certain conditions are met.

:::warning
This feature relies on [Promise](https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Reference/Global_Objects/Promise) internally. If you use `require.ensure` with older browsers, remember to shim Promise using a polyfill such as [es6-promise](https://github.com/stefanpenner/es6-promise) or [promise-polyfill](https://github.com/taylorhakes/promise-polyfill).
:::

- **Type:**

```ts
function requireEnsure(
  /**
   * An array of strings declaring all modules required for the code in the callback to execute.
   */
  dependencies: String[],
  /**
   * A function that webpack will execute once the dependencies are loaded.
   * An implementation of the require function is sent as a parameter to this function.
   * The function body can use this to further require() modules it needs for execution
   */
  callback: function(require),
  /**
   * A function that is executed when webpack fails to load the dependencies.
   */
  errorCallback?: function(error),
  /**
   * A name given to the chunk created by this particular require.ensure().
   * By passing the same chunkName to various require.ensure() calls,
   * we can combine their code into a single chunk, resulting in only one bundle that the browser must load.
   */
  chunkName?: string
): Context;
```

- **Example:**

```ts
var a = require('normal-dep');

if (module.hot) {
  require.ensure(['b'], function (require) {
    var c = require('c');

    // Do something special...
  });
}
```

### require.resolveWeak

<ApiMeta specific={['Rspack', 'Webpack']} />

Similar to `require.resolve`, but this method won't pull the module into the final bundle. It's what is considered a "weak" dependency.

```js
require.resolveWeak(dependency: string);
```

For example:

```js
if (__webpack_modules__[require.resolveWeak('module')]) {
  // Do something when module is available...
}
if (require.cache[require.resolveWeak('module')]) {
  // Do something when module was loaded before...
}

// You can perform dynamic resolves ("context")
// similarly to other require/import methods.
const page = 'Foo';
__webpack_modules__[require.resolveWeak(`./page/${page}`)];
```

## Data URI module

Rspack supports importing Data URI modules using the `import` and `require` syntax.

- **import**

```js
import DataURI from 'data:text/javascript,export default 42';
```

- **require**

```js
require('data:text/javascript,module.exports = 42');
```

In addition, Base64 encoded requests are also supported:

```js
const {
  number,
  fn,
} = require('data:text/javascript;charset=utf-8;base64,ZXhwb3J0IGNvbnN0IG51bWJlciA9IDQyOwpleHBvcnQgZnVuY3Rpb24gZm4oKSB7CiAgcmV0dXJuICJIZWxsbyB3b3JsZCI7Cn0=');
```

::: tip
The Data URI module can be used as a method to implement virtual modules, such as combining with a Loader to dynamically load custom modules at runtime.
:::

### Built-in rules

Rspack supports these [MIME types](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/MIME_types) for data URI modules by default: `application/json`, `text/javascript`, `application/javascript`, `application/node`, and `application/wasm`. This means that when you create data URI modules with these MIME types, Rspack will automatically recognize them.

Rspack's built-in MIME rules are as follows:

```js
const defaultMimeRules = [
  {
    mimetype: 'application/node',
    type: 'javascript/auto',
  },
  {
    mimetype: 'application/json',
    type: 'json',
  },
  {
    mimetype: {
      or: ['text/javascript', 'application/javascript'],
    },
    type: 'javascript/esm',
    // ...
  },
  {
    mimetype: 'application/wasm',
    type: 'webassembly/async',
    // ...
  },
];
```

### Custom rules

You can also use [Rule.mimetype](/config/module#rulemimetype) to extend the matching rules for Data URI modules, for example, to add custom loaders for `text/javascript`:

```js title="rspack.config.mjs"
export default {
  module: {
    rules: [
      {
        mimetype: 'text/javascript',
        use: [
          // ...
        ],
      },
    ],
  },
};
```
